<?php
/**
 *    Copyright 2010 Show Framework(www.showframework.cn)
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 * 
 *        http://www.apache.org/licenses/LICENSE-2.0
 * 
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

/**
 * Show_Db_Handle_Interface
 * 对数据库驱动功能的定义
 * 
 * @package Show_Db_Handle
 * @name Show_Db_Handle_Interface
 * @author show
 * @since v0.6
 */
interface Show_Db_Handle_Interface
{
    /**
     * Get number of affected rows in previous MySQL operation
     * Returns the number of rows affected by the last INSERT, UPDATE, REPLACE or DELETE query.
     * > 0 
     * 0 no records affected
     * -1 error
     * 
     * @return int
     */
    public function affected();
    
    /**
     * Closes a previously opened database connection
     *
     * @return bool
     */
    public function close();
    
    /**
     * Move internal result pointer
     * Returns TRUE on success or FALSE on failure. 
     *
     * @param int $offset
     * @return bool
     */
    public function seek($offset);
    
    /**
     * Returns the numerical value of the error message from previous MySQL operation
     * zero means no error occurred.
     *
     * @return int
     */
    public function errno();
    
    /**
     * Returns the text of the error message from previous MySQL operation
     * An empty string if no error occurred.
     *
     * @return string
     */
    public function error();
    
    /**
     * Fetch a result row as an associative array, a numeric array, or both or object
     * 
     * @param int $fetchMode
     * @return array|object|false
     */
    public function fetch($fetchMode = Show_DB::FETCH_ASSOC);
    
    /**
     * Frees the memory associated with a result
     * 
     * @return bool
     */
    public function free();
    
    /**
     * Get the ID generated from the previous INSERT operation
     * Retrieves the ID generated for an AUTO_INCREMENT column by the previous INSERT query.
     * > 0 or 0
     *
     * @return int
     */
    public function insertId();
    
    /**
     * Gets the number of rows in a result
     * > 0 or 0
     *
     * @return int
     */
    public function rows();
    
    /**
     * Send a SQL query
     *
     * @param string $sql
     * @return bool
     */
    public function query($sql);
    
    /**
     * Escapes special characters in a string for use in a SQL statement
     *
     * @param string $string
     * @return string
     */
    public function escape($string);
    
    /**
     * Selects the default database for database queries
     *
     * @param string $name
     * @return bool
     */
    public function db($name);
    
    /**
     * Sets the client character set
     *
     * @param string $charset
     * @return bool
     */
    public function charset($charset);
}
?>